package com.example.demo.repository;

import com.example.demo.entity.CopyrightEntity;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import java.util.List;
import java.util.Optional;

/**
 * 版权数据访问接口
 * <p>
 * Spring Data JPA会根据接口中定义的方法名称自动生成实现。
 * 继承JpaRepository后会自动拥有基本的CRUD操作方法，如save(), findById(), findAll()等。
 */
@Repository
public interface CopyrightRepository extends JpaRepository<CopyrightEntity, Long> {
    
    /**
     * 根据区块链ID查找版权
     * 
     * @param blockchainId 区块链ID
     * @return 版权实体
     */
    Optional<CopyrightEntity> findByBlockchainId(String blockchainId);
    
    /**
     * 根据所有者地址查找版权并按创建时间降序排序
     * <p>
     * 方法名解析：
     * - findBy: 定义这是一个查询方法
     * - OwnerAddress: 查询条件，匹配CopyrightEntity中的ownerAddress属性
     * - OrderBy: 表示排序开始
     * - CreateTime: 排序字段，匹配实体中的createTime属性
     * - Desc: 降序排序(最新的排在前面)
     * 
     * 等效SQL: SELECT * FROM copyright WHERE owner = ? ORDER BY create_time DESC
     * 
     * @param ownerAddress 所有者区块链地址(以0x开头的42字符)
     * @return 按创建时间降序排列的版权列表
     */
    List<CopyrightEntity> findByOwnerAddressOrderByCreateTimeDesc(String ownerAddress);

    /**
     * 根据图片哈希查找版权
     * <p>
     * 方法名解析：
     * - findBy: 定义这是一个查询方法
     * - ImageHash: 查询条件，匹配CopyrightEntity中的imageHash字段
     *
     * 此方法用于检查特定图片是否已在区块链上注册版权。
     * 正常情况下一个图片哈希应只有一个有效版权，但考虑到可能的版权转让历史，
     * 因此返回类型为List而非单个实体。
     *
     * 等效SQL: SELECT * FROM copyright WHERE image_hash = ?
     *
     * @param imageHash 图片哈希值(通常为64个十六进制字符)
     * @return 与该图片哈希关联的所有版权记录
     */
    List<CopyrightEntity> findByImageHash(String imageHash);

    /**
     * 根据所有者地址和有效性状态查找版权并按创建时间降序排序
     * <p>
     * 方法名解析：
     * - findBy: 定义这是一个查询方法
     * - OwnerAddress: 第一个查询条件，匹配实体的ownerAddress字段
     * - And: 逻辑AND连接多个条件
     * - IsValid: 第二个查询条件，匹配实体的isValid字段
     * - OrderBy: 表示排序开始
     * - CreateTime: 排序字段
     * - Desc: 降序排序
     *
     * 此方法主要用于获取用户当前有效的版权，过滤掉已失效的版权记录。
     * 版权可能因各种原因失效，如转让给他人、被撤销等。
     *
     * 等效SQL: SELECT * FROM copyright WHERE owner = ? AND is_valid = ? ORDER BY create_time DESC
     *
     * @param ownerAddress 所有者区块链地址
     * @param isValid 版权有效状态(true表示有效)
     * @return 指定所有者的有效版权列表，按创建时间降序排列
     */
    List<CopyrightEntity> findByOwnerAddressAndIsValidOrderByCreateTimeDesc(String ownerAddress, Boolean isValid);

    /**
     * 检查区块链ID是否存在
     *
     * @param blockchainId 区块链ID
     * @return 是否存在
     */
    boolean existsByBlockchainId(String blockchainId);

    /**
     * 根据图片哈希和有效状态查找版权
     */
    List<CopyrightEntity> findByImageHashAndIsValidOrderByCreateTimeDesc(String imageHash, Boolean isValid);

    /**
     * 检查图片哈希是否存在
     */
    boolean existsByImageHash(String imageHash);

    /**
     * 通过图片哈希查询版权列表，按创建时间倒序排序
     * @param imageHash 图片哈希
     * @return 版权实体列表
     */
    List<CopyrightEntity> findByImageHashOrderByCreateTimeDesc(String imageHash);
    
    /**
     * 通过所有者地址和有效状态查询版权列表，按创建时间倒序排序
     * @param ownerAddress 所有者地址
     * @return 有效版权实体列表
     */
    List<CopyrightEntity> findByOwnerAddressAndIsValidTrueOrderByCreateTimeDesc(String ownerAddress);
    
    /**
     * 通过图片哈希和有效状态查询版权列表，按创建时间倒序排序
     * @param imageHash 图片哈希
     * @return 有效版权实体列表
     */
    List<CopyrightEntity> findByImageHashAndIsValidTrueOrderByCreateTimeDesc(String imageHash);
} 